home *** CD-ROM | disk | FTP | other *** search
/ TOS Silver 2000 / TOS Silver 2000.iso / Anwendun / 7UP_PD / TOOLBAR.TXT < prev    next >
Encoding:
Text File  |  1997-01-17  |  11.6 KB  |  328 lines
  1. Window Library Enhancements - Toolbar Support
  2.  
  3. 11.1  Introduction
  4.  
  5. This  section describes the additional features of the Window Library.
  6. All  enhancements  are  backwards compatible with previous versions of
  7. the  AES,  so  existing  applications  will  continue to work. The new
  8. feature  will  work  on  all machines with an AES version greater than
  9. 4.1.
  10.  
  11.  
  12. The enhancements to the Window Library are:
  13.  
  14. o  Toolbar support has been added to the AES.
  15. o  wind_set() may be used to attach, change or remove a Toolbar from a window.
  16. o  wind_get() may be used to see which Toolbar, if any, is attached to a
  17. window.  In
  18. addition, wind_get() may be used to get the the Toolbar rectangle list for
  19. custom
  20. redraws.
  21. o  Mouse clicks on objects within the Toolbar generate Message Events.
  22. o  GEM AES will handle the Toolbar when a window needs to be moved, sized or
  23. redrawn.
  24.  
  25.  
  26. 11.2.1  Toolbar Introduction
  27.  
  28. A  Toolbar  is an OBJECT tree that is located below the INFO line of a
  29. window  but  above  the  work  area. Toolbars are a convenient way for
  30. applications to display button and status information.
  31.  
  32.  
  33. 11.2.2  Division of Labor
  34.  
  35. GEM  AES  and the application divide responsibility for proper TOOLBAR
  36. management. GEM AES's responsibilities include the following:
  37.  
  38. o  Updating the x and y position of the Toolbar when the window is moved, sized
  39. and/or
  40. fulled.
  41. o  Ensuring that the  window is configured to the size required for the window
  42. parts and
  43. Toolbar.
  44. o  Setting the width of the Toolbar ( ROOT )  to be the width of the window.
  45. o  Redrawing the Toolbar when a WM_REDRAW message is received.
  46. o  Sending a Message Event to the application whenever the user clicks on a
  47. TOUCHEXIT
  48. object within the Toolbar.  The state of the SHIFT, ALT and CTRL keys and the
  49. number of
  50. button clicks that occurred are also sent.
  51.  
  52.  
  53. The application is responsible for the following:
  54.  
  55. o  Building an object tree with any buttons designated as TOUCHEXITs.
  56. o  If the Toolbar contains any child objects that are meant to be the width of
  57. the window,
  58. the application is responsible for changing the ob_width of that object.  The
  59. width would
  60. normally have to be changed whenever the application receives a FULLER and/or a
  61. SIZER message.
  62. o  Handling user-defined objects within the Toolbar.
  63. o  Redrawing any objects that changes their visual appearance.  The application
  64. must take
  65. care that the redraw is properly clipped to the window.  This is done by
  66. walking the
  67. rectangle list of the Toolbar and redrawing accordingly.
  68. o  Screen resolution differences are up to the application to resolve.  For
  69. example, the
  70. height of an icon in ST Medium is different than in TT Medium.
  71. o  The colors used by the Toolbar are the responsibility of the application.
  72.  
  73.  
  74. 11.2.3  Window Management Calls
  75.  
  76. An application will use the calls below to manage the Toolbar.
  77.  
  78. o  To attach a Toolbar to a window, the application should call wind_set( wid,
  79. WF_TOOLBAR, ... ); with the address of the Toolbar.  If the call is made while
  80. the
  81. window is open, the window will adjust itself  to take into account the height
  82. of the
  83. Toolbar.
  84.  
  85. o  To change the Toolbar from one Toolbar to another, the application should
  86. call
  87. wind_set( wid, WF_TOOLBAR, ... ); with the address of the new Toolbar.  If the
  88. call is
  89. made while the window is open, the window will adjust itself to take into
  90. account the
  91. height of the new Toolbar.
  92.  
  93. o  To remove the Toolbar from the window, the application need only call
  94. wind_set( wid,
  95. WF_TOOLBAR, ... ); with NULL parameters.  If the call is made while the window
  96. is
  97. open, the window will adjust itself to take into account the lack of a Toolbar.
  98.  
  99. o  Closing a window with wind_close() does not remove the Toolbar from the
  100. window  In
  101. this way, the application may reopen the window with the Toolbar still present.
  102.  
  103. o  Deleting a window with wind_delete() will remove any attached Toolbar.
  104.  
  105. o  To receive mouse clicks on Toolbar objects, all button objects should be set
  106. to
  107. TOUCHEXIT.  When the user clicks on a TOUCHEXIT, GEM AES generates a Message
  108. Event.  The message WM_TOOLBAR has a maximum length of 16 bytes and is defined
  109. as:
  110.  
  111.    o  word 0   -  WM_TOOLBAR
  112.    o  word 1   -  ap_id of the application that sent the message.
  113.    o  word 2   -  0
  114.    o  word 3   -  the handle of the window
  115.    o  word 4   -  the object click on
  116.    o  word 5   -  the number of clicks
  117.    o  word 6   -  the state of the SHIFT, ALT and CTRL keys
  118.    o  word 7   -  0
  119.  
  120.  
  121. 11.2.4  Support of Overlapping Windows
  122.  
  123. GEM AES can handle the redraws for the Toolbar when windows overlap.  However,
  124. a window
  125. with a Toolbar will not generate any Message Events unless it is the TOP
  126. window.
  127.  
  128.  
  129. 11.2.5  Redrawing and Updating
  130.  
  131. To redraw the Toolbar, the application should walk the rectangle list.  The
  132. current way to get
  133. the rectangle list is to call wind_get() with WF_FIRSTXYWH and WF_NEXTXYWH.
  134. However,
  135. these parameters will only return the rectangles for the work area of the
  136. window.  Therefore, in
  137. order to get the rectangle list for the Toolbar area, the application should
  138. call wind_get() with
  139. WF_FTOOLBAR and WF_NTOOLBAR, which will return the first Toolbar rectangle and
  140. the next
  141. Toolbar rectangle respectively.
  142.  
  143.  
  144. The application will need to redraw the Toolbar for the following:
  145.  
  146. o  If the Toolbar contains a user-defined object, the redraw must be done by
  147. the support
  148. code for that object.  Since the window will not necessarily be the top window,
  149. redrawing
  150. via the rectangle list is crucial.
  151.  
  152. o  If the application changes the state of an object within the Toolbar, the
  153. object will need
  154. to be redrawn.  For example, the application changes the ob_state of a button
  155. to
  156. SELECTED.  The dirty area will consist of the object's rectangle plus the
  157. effects of any 3D,
  158. Shadowing, outline etc..  Again, since the window will not necessarily be the
  159. top window,
  160. redrawing via the rectangle list is crucial.
  161.  
  162.  
  163. The application may have to update the Toolbar for the following:
  164.  
  165. o  If the Toolbar contains an object that is meant to be the width of the
  166. window AND is not
  167. the ROOT object, the application will need to set the width of the object in
  168. response to
  169. several Message Events.  These messages include FULLER and SIZER events.
  170. Simply set
  171. the width of the object before calling wind_set( wid, WF_CURRXYWH, ... );  to
  172. set the
  173. new current size of the window.
  174.  
  175. o  If the window is iconified, the application need not handle the Toolbar
  176. until the window
  177. is no longer iconified.
  178.  
  179. o  If the window is sized and/or fulled such that the width of the window is
  180. smaller than
  181. the Toolbar, the Toolbar will merely be clipped.  Buttons that are clipped are
  182. obviously
  183. not accessible.  In these situations, the application may elect to change the
  184. height of the
  185. Toolbar and reposition the buttons at its discretion.  When the applications
  186. calls
  187. wind_set( wid, WF_CURRXYWH, ... ) to set the new current size of the window,
  188. GEM
  189. AES will rebuild the window based upon the new height of the Toolbar.
  190.  
  191. o  If the application wishes to merely switch one Toolbar with another, the
  192. application
  193. should call wind_set( wid, WF_TOOLBAR, ... ) with the new OBJECT tree.
  194.  
  195. o  In the same instance, if the application wishes to remove the Toolbar, the
  196. application
  197. should call wind_set( wid, WF_TOOLBAR, ... ) with NULL parameters.
  198.  
  199.  
  200. 11.3  Window Library Routines - Toolbar Support Addendum
  201.  
  202. The Toolbar code affect the following routines.  For more information about
  203. these and other
  204. routines, please see the GEM AES documentation.
  205.  
  206. 11.3.5  WIND_GET() - Gets information on a particular window
  207.  
  208.    #include <aes.h>
  209.  
  210.    result=wind_get( handle, field, x,y,w,h );
  211.  
  212.    WORD  result   error result
  213.    WORD  handle;  window handle
  214.    WORD  field;   information wanted
  215.    WORD  *x;   value depends upon information requested
  216.    WORD  *y;   value depends upon information requested
  217.    WORD  *w;   value depends upon information requested
  218.    WORD  *h;   value depends upon information requested
  219.  
  220. The Toolbar field values are:
  221.  
  222.    WF_TOOLBAR  -  30
  223.       -  x and y give the address of the Toolbar object tree.
  224.       -  x is the high word of the address
  225.       -  y is the low word of the address
  226.  
  227.    WF_FTOOLBAR -  31
  228.       -  the coordinates of the first rectangle in the Toolbar's rectangle
  229. list.
  230.       -  x ( X - coordinate )
  231.       -  y ( Y - coordinate )
  232.       -  w ( width )
  233.       -  h  ( height )
  234.  
  235.    WF_NTOOLBAR -  32
  236.       -  the coordinates of the next rectangle in the Toolbar's rectangle list.
  237.       -  x ( X - coordinate )
  238.       -  y ( Y - coordinate )
  239.       -  w ( width )
  240.       -  h ( height )
  241.  
  242.  
  243. 11.3.6  WIND_SET() - Sets new values for the fields that determine how a
  244. window is displayed.
  245.  
  246.    #include <aes.h>
  247.  
  248.    result=wind_set( handle, field, x,y,w,h );
  249.  
  250.    WORD  result   error result
  251.    WORD  handle;  window handle
  252.    WORD  field;   information to set
  253.    WORD  x; value depends upon field
  254.    WORD  y; value depends upon field
  255.    WORD  w; value depends upon field
  256.    WORD  h; value depends upon field
  257.  
  258. The Toolbar field values are:
  259.  
  260.    WF_TOOLBAR  -  30
  261.       -  Used to attach, change or remove a Toolbar.  To remove a Toolbar, set
  262. (x,y)
  263. to NULL.
  264.       -  x is the high word of the address
  265.       -  y is the low word of the address
  266.  
  267.  
  268. 11.3.9  WIND_CALC()  -  Calculates  the  X-  and Y-coordinates and the
  269. width and height of a window's work area or border area.
  270.  
  271. This  routine  calculates  the  X  and Y coordinates and the width and
  272. height  of  a window's work area or border area. wind_calc() does this
  273. by  adding up the widths and heights of the window parts passed in via
  274. 'kind'.  Since  no  window  handle  is  involved,  wind_calc()  cannot
  275. calculate  the  work  area  or  border  area  of  a window that has an
  276. attached Toolbar.
  277.  
  278. However,  it  is  possible  to  adjust  the  values returned since the
  279. application  knows  about the height of the Toolbar. The height of the
  280. Toolbar   should   include  the  area  occupied  by  any  3D  effects,
  281. shadowing, border thickness etc..
  282.  
  283. To  compensate  for  the  Toolbar,  simply  increase the height of the
  284. border  area by the height of the Toolbar. In addition, since the work
  285. area  is  below  the  Toolbar, increase the y - coordinate of the work
  286. area by the same amount. The height of the work area remains the same.
  287.  
  288.  
  289. 11.4  DEFINES
  290.  
  291. Please  be  sure  to  include these defines in your AES.H include file
  292. for your compiler.
  293.  
  294.    #define  WF_TOOLBAR  30 Toolbar parameter for wind_get/set
  295.    #define  WF_FTOOLBAR 31 Get the First Toolbar rectangle
  296.    #define  WF_NTOOLBAR 32 Get the Next Toolbar rectangle
  297.    #define  WM_TOOLBAR  37 Toolbar Button Event Message
  298.  
  299.  
  300. Event Library Enhancements - Toolbar Support
  301.  
  302. 4.2.5.1 Predefined GEM AES Messages
  303.  
  304. The  Toolbar  adds  a  new  Message  Event to the existing list of AES
  305. Messages.  For additional information on the Event Library, please see
  306. the AES Documentation.
  307.  
  308. GEM  AES  provides  several  predefined message types. Each type has a
  309. maximum  length  of  16 bytes. All the predefined message types define
  310. the first three words in the same way:
  311.  
  312. o  WORD  0  -  A number identifying the message type.
  313. o  WORD  1  -  The ap_id of the application that sent the message.
  314. o  WORD  2  -  The length of the message, not counting the predefined 16 bytes.
  315.  
  316.  
  317. 4.2.5.14 WM_TOOLBAR
  318.  
  319. GEM  AES  uses  this  message  to  tell  the application which Toolbar
  320. object  the  mouse  clicked on. The object must be a TOUCHEXIT and not
  321. disabled. In addition, the window must be the TOP window.
  322.  
  323.    o  WORD  0  37
  324.    o  WORD  3  the handle of the application's window
  325.    o  WORD  4  the Toolbar object clicked on
  326.    o  WORD  5  the number of mouse button clicks
  327.    o  WORD  6  the state of the SHIFT, ALT and CTRL keys
  328.